ShareWare OnLine 2/ShareWare OnLine Volume 2 (CMS Software)(1993).iso/prog/strpp212.zip/STR.DOC

Text File | 1993-02-17 | 14KB | 367 lines

                           String++ Version 2.12

                      Copyright 1992 by Carl Moreland
                                 02/16/93

---------------------------------------------------------------------------

    String++  is a string class written for Borland/Turbo C++.  To use  the
string  class in your program,  simply add str.lib to your project or  make
file and #include str.h in any module that uses a string.  str.lib contains
all the functions in str.cpp,  but the functions are separated into differ-
ent  object modules for greater efficiency.  Note that str.lib is  compiled
for the large memory model.

    Strings may be declared or initialized in the following ways:

        string str;                     // NULL string
               str('H');                // single character
               str = 'H';               // single character
               str(ch);                 // single character ch
               str = ch;                // single character ch
               str(ch, 5);              // make 5 copies of ch
               str("Hello World");      // char*
               str = "Hello World";     // char*
               str(ptr);                // char *ptr
               str = ptr;               // char *ptr
               str(ptr, 5);             // begin at ptr[5]
               str(ptr, 5, 3);          // begin at ptr[5], use 3 chars
               str(str1);               // another string
               str = str1;              // another string
               str(str1, 5);            // begin at str1[5]
               str(str1, 5, 3);         // begin at str1[5], use 3 chars
               str(45);          // convert an int to a string

Unlike  many  other string classes,  this class does  not  utilize  minimum
string buffer sizes, such as 10 characters. Minimum length strings have the
advantage of reduced memory management if the manipulated string is  always
less than the minimum size;  however, the penalty is that every string will
be  at  least the minimum size.  As always,  it's a tradeoff of  speed  vs.
memory.

The following operators are available:

        =       see above
        ()      str() returns the char* of the string
        []      str[i] returns the ith character of str; [] can also assign
                the ith character of a string.
        +  +=   concatenates
        *  *=   multiple duplicates
        == !=   comparisons
        <  >    comparisons
        <= >=   comparisons

There is also a cast operator which returns type const char*. This allows a
string  object to be directly used as a parameter in most C and  C++  func-
tions without having to use the () operator:

    char *p;
    strcpy(p, s1);        // where s1 is a string

The "+" operator and all comparison operators are declared as friend  func-
tions.  This enables them to accept char, char*, and string as valid  argu-
ments  on either side of the operator.  Therefore, each of these statements
is valid:

        str1 = "Hello" + str2;
        str1 = str2 + "World";
        str1 = "Hello" + str2 + "World";
        if(str1 == "Hello World") ...
        if("Hello World" == str1) ...

Technically,  most  of the operators do not need  overloading  because  the
string  constructors  will  automatically  convert the  arguments  to  type
string.  The advantage is that fewer functions must be coded,  which  saves
memory. The disadvantage is that there is a speed penalty because construc-
tors (might) have to be called to convert arguments.  The class was  tested
both ways and it was found that the added code was small, but the speed was
more than doubled when using overloaded operators. Therefore, the operators
are overloaded to accept string and char*.  There are no overloads for type
char parameters because it would most probably be a rare case, and the con-
structor can pick it up. Besides, the two following statements are entirely
equivalent:

        if(str1 == 'a') ...
        if(str1 == "a") ...

    Finally, the demo program str_test.cpp contains a suite of string mani-
pulations which demonstrate most of the string functions.

---------------------------------------------------------------------------
---------------------------------------------------------------------------

Class Functions:

---------------------------------------------------------------------------
int Length(void) const;
int Len(void)    const;

Both functions return the length of the string:

        str = "Hello World";

        i = str.Length();               // i = 11

---------------------------------------------------------------------------
string& Left(int len);
string& Right(int len);
string& Mid(int pos, int len);

These functions return substrings of a string:

        str1 = str2 = str3 = "This is a test";

        str1.Left(4);            // str1 = "This"
        str2.Mid(5, 4);            // str2 = "is a"
        str3.Right(4);            // str3 = "test"

---------------------------------------------------------------------------
string& Justify(int mode, int len, int clip=0);

This function justifies a string by padding it with spaces (0x20) until  it
is 'len' long.  If the original string had any leading  or  trailing  white
spaces then they are first removed.  If the original string is longer  than
'len' (after removal of white spaces) then it is clipped to len if  clip=1,
otherwise the trimmed string is returned.

        str1 = str2 = str3 = "Hello World";

        str1.Justify(LEFT, 20);        // str1 = "Hello World         "
        str2.Justify(CENTER, 20);    // str2 = "    Hello World     "
        str3.Justify(RIGHT, 20);    // str3 = "         Hello World"

---------------------------------------------------------------------------
string& Trim(int mode = CENTER, char ch = WHITESPACE);

This function can trim leading or trailing characters from a string. The
trimmed character defaults to WHITESPACE (spaces & tabs) and can be user-
defined.

    str1 = str2 = str3 = "    Spaces    ";

        str1.Trim(LEFT);        // str1 = "Spaces    "
        str2.Trim(RIGHT);        // str2 = "    Spaces"
        str3.Trim();            // str3 = "Spaces"

---------------------------------------------------------------------------
string& Insert(unsigned pos, const string& s);

Inserts a substring at position pos.

    str = "This a test";

        str.Insert(5, "is ");        // str = "This is a test"

---------------------------------------------------------------------------
string& Delete(unsigned pos, unsigned len = 10000);

Deletes a substring beginning at position pos with length len.

    str = "This is a test";

        str.Delete(5, 3);        // str = "This a test"

---------------------------------------------------------------------------
char* Copy(char*&);

Copies  the  string  contents to a non-const character pointer.  Copy  will
allocate the memory for the pointer - it is up to you to free (delete)  it.
Normally, the contents of a string are extracted with the ()operator or the
cast operator.  However,  this returns a const char* that must be cast to a
non-const char* for many C-style functions (most Borland library  functions
will accept const char*).

    s1 = "lowercase";
    strupr(s1);        // won't work - strupr() expects char*
        strupr((char*)s1);    // cast to char* - this works

    char* p;
        s1.Copy(p);        // copy str to char *p
        strupr(p);        // normal C-style

Although  you could also use the ptr() method to return a non-const  char*,
this  is considered unsafe as it completely strips the inherent  protection
that the string class offers.

---------------------------------------------------------------------------
int Index(const string& t);

Member method of the AWK function index().

---------------------------------------------------------------------------
string SubStr(unsigned p, unsigned n=10000);

Member method of the AWK function substr().

---------------------------------------------------------------------------
int Split(string*& a, const string& fs);

Member method of the AWK function split().

---------------------------------------------------------------------------
int Sub(const string& from, const string& to, unsigned count=10000);

Member method of the AWK function gsub().

---------------------------------------------------------------------------
string& toUpper(void);
string& toLower(void);

These functions convert the string to upper or lower case,  and also return
the converted string.

        str1 = "uppercase";
        str2 = "LOWERCASE";

        str1.toUpper();                 // str1 is now "UPPERCASE"
        str2.toLower();                 // str2 is now "lowercase"

---------------------------------------------------------------------------
int&  Value(int& n);
long& Value(long& n);

Returns the value of a numeric string.

        int n1;
    str = "12345";

        str.Value(n1);            // n1 is now 12345

---------------------------------------------------------------------------
---------------------------------------------------------------------------

Awk-style Functions:

Note: AWK  begins array indexing at 1, whereas C/C++ begins array  indexing
      at 0.  Therefore, most of the implemented AWK functions return values
      that correspond to C-style indexing.  An AWK function that might nor-
      mally return a 0 as a failure indicator will return a -1 here.

---------------------------------------------------------------------------
int length(string& s);

Returns the length of a string:

        str = "Hello World";

        i = length(str);                // i = 11

---------------------------------------------------------------------------
int index(string& s, string& t);

Returns the position of 't' in 's' if it exists, or -1 if it doesn't:

        str = "d:\\prog\\str"

        i = index(str, ":");            // i = 1

---------------------------------------------------------------------------
string substr(string& s, unsigned int p, unsigned int n=10000);

Returns the substring of 's' beginning at position 'p' with length 'n':

        str1 = "Don't just stand there...";

        str2 = substr(str, 11, 5);      // str2 = "stand"

---------------------------------------------------------------------------
int split(string& s, string*& a, string& fs);

Splits  string 's' into an array 'a' on field separator 'fs'.  Array 'a' is
normally  declared  as  an uninitialized pointer in  the  calling  function
(string *a),  and a reference to the pointer is passed to split().  split()
will then allocate memory for the correct array size and return the  number
of fields:

        string *array;
        str = "d:\\prog\\str";

        i = split(str, array, "\\";    // i = 3
        // array[0] = "d:"
    // array[1] = "prog"
    // array[2] = "str"

---------------------------------------------------------------------------
int sub(string& from, string& to, string& str);

Substitute  'to'  for the leftmost substring of 'str' that  is  matched  by
'from'. Return the number of substitutions (0 or 1). This function actually
calls gsub() with num=1;

        str = "d:\\prog\\str";

        i = sub("\\", "/", str);        // i = 1
        // str = "d:/prog\str"

---------------------------------------------------------------------------
int gsub(string& from, string& to, string& str, int num=10000);

Substitute 'to' for 'from' globally in string 'str' up to 'num' times.  Re-
turn the number of substitutions.

        str = "d:\\prog\\str";
        i = gsub("\\", "/", str);       // i = 2
        // str = "d:/prog/str"

---------------------------------------------------------------------------
---------------------------------------------------------------------------

C-Style Functions:

---------------------------------------------------------------------------
string toupper(string& s);
string tolower(string& s);

These  functions return the upper- or lowercase versions of a  string.  The
string itself is not modified.

        str1 = "uppercase";
        str2 = "LOWERCASE";

        str3 = toupper(str1);           // str3 = "UPPERCASE"
        str4 = tolower(str2);           // str4 = "lowercase"

---------------------------------------------------------------------------
string right(string& s, int n);
string left(string& s, int n);
string mid(const string& s, int p, int n);

These functions return substrings of a string:

        str = "This is a test";

        str1 = left(str, 4);            // str1 = "This"
        str2 = mid(str, 5, 4);          // str2 = "is a"
        str3 = right(str, 4);           // str3 = "test"

---------------------------------------------------------------------------
string justify(string& s, int mode, int len, int clip=0);

This function justifies a string by padding it with spaces (0x20) until  it
is 'len' long.  If the original string had any leading  or  trailing  white
spaces then they are first removed.  If the original string is longer  than
'len' (after removal of white spaces)  then it is clipped to len if clip=1,
otherwise the trimmed string is returned.

        str = "Hello World";

        str1 = justify(str, LEFT, 20);   // str1 = "Hello World         "
        str2 = justify(str, CENTER, 20); // str2 = "    Hello World     "
        str3 = justify(str, RIGHT, 20);  // str3 = "         Hello World"

---------------------------------------------------------------------------
string trim(string& s, int mode = CENTER, char ch = WHITESPACE);

This function can trim leading or trailing characters from a string. The
trimmed character defaults to WHITESPACE (spaces & tabs) and can be user-
defined.

    str = "    Spaces    ";

        str1 = trim(str, LEFT);        // str1 = "Spaces    "
        str2 = trim(str, RIGHT);    // str2 = "    Spaces"
        str3 = trim(str);        // str3 = "Spaces"

---------------------------------------------------------------------------